JIIT Placement Alerts

Documentation

Back to Home
Live GitHub
Getting Started

Architecture & Design

API Architecture & Endpoints
Error Handling & Rate Limiting REST API Endpoints Server Architecture Telegram Bot API
Data Flow & Processing Pipeline
Email Processing Orchestration Notification Flow Distribution Update Flow Processing
Database Schema & Data Model
Collection Schemas & Field Definitions Data Flow & Collection Relationships Indexing Strategy & Performance Optimization Query Patterns & Practical Examples
Service Architecture
Administrative Services Content Processing Services Core Services Formatting Services
Deployment Architecture Design Principles

Core Services

Email Processing Services
Email Notice Service Notice Formatter Service Placement Notification Formatter Placement Service
Database Service Notification Service Telegram Service Web Push Service

Data Processing & Content Extraction

Content Formatting & Enhancement Email Processing & Classification LLM Powered Content Extraction Statistics Calculation & Analytics

Server Components

Scheduler Server Telegram Bot Server Webhook Server
API Reference
Configuration & Environment
Database Schema & Models
Deployment & Operations
Development & Contributing
Troubleshooting & FAQ
Home Projects JIIT Placement Alerts Architecture & Design Deployment Architecture

Deployment Architecture

Referenced Files
main.pydaemon.pyconfig.pybot_server.pywebhook_server.pyscheduler_server.pyupdate_runner.pynotification_runner.pyrequirements.txt
#

Table of Contents#

  1. Introduction

  2. Project Structure

  3. Core Components

  4. Architecture Overview

  5. Detailed Component Analysis

  6. Dependency Analysis

  7. Performance Considerations

  8. Troubleshooting Guide

  9. Conclusion

#

Introduction#

This document describes the deployment and operational architecture of the SuperSet Telegram Notification Bot. The system is organized around a unified CLI that coordinates three distinct operational modes:

  • Telegram bot server for user interactions and administrative commands

  • FastAPI webhook server for REST APIs and health checks

  • Scheduler server for automated update cycles

The architecture emphasizes daemon mode operation, robust process management, configurable scheduling with APScheduler, and comprehensive logging strategies suitable for both development and production environments.

#

Project Structure#

The application follows a modular structure with clear separation of concerns:

  • CLI entry point orchestrating all operations

  • Core utilities for configuration and daemon management

  • Server implementations for Telegram, webhook, and scheduler

  • Runner modules encapsulating update and notification logic

  • Services and clients for external integrations

graph TB CLI["CLI Entry Point
app/main.py"] --> Bot["Telegram Bot Server
app/servers/bot_server.py"] CLI --> Webhook["Webhook Server
app/servers/webhook_server.py"] CLI --> Scheduler["Scheduler Server
app/servers/scheduler_server.py"] Bot --> Config["Configuration
app/core/config.py"] Webhook --> Config Scheduler --> Config Bot --> Daemon["Daemon Utilities
app/core/daemon.py"] Scheduler --> Daemon Bot --> UpdateRunner["Update Runner
app/runners/update_runner.py"] Scheduler --> UpdateRunner Webhook --> NotificationRunner["Notification Runner
app/runners/notification_runner.py"]

Diagram sources

Section sources

#

Core Components#

The deployment architecture centers on four primary components:

CLI Orchestration Layer#

The main entry point provides a unified interface for all operational modes:

  • Command parsing with subcommands for bot, scheduler, webhook, and data operations

  • Global daemon mode flag propagation

  • Centralized logging initialization with verbose mode support

  • Graceful error handling and user interruption management

Daemon Management System#

Unix-style daemonization with:

  • Double-fork process isolation

  • PID file management for process tracking

  • Signal-based graceful shutdown

  • Automatic cleanup of stale PID files

  • Separate logging redirection for daemon processes

Scheduling Infrastructure#

APScheduler-based automation with:

  • Configurable update cycles across multiple IST time slots

  • Independent scheduler server decoupled from the Telegram bot

  • Job persistence and restart resilience

  • Timezone-aware scheduling with Asia/Kolkata timezone

Operational Servers#

Three specialized servers with distinct responsibilities:

  • Telegram bot server with command handlers and administrative controls

  • FastAPI webhook server with health checks and notification endpoints

  • Scheduler server orchestrating automated update workflows

Section sources

#

Architecture Overview#

The system operates as a distributed set of cooperating processes, each designed for specific operational tasks:

graph TB subgraph "Operational Processes" BotProc["Bot Process
Telegram Bot Server"] SchedProc["Scheduler Process
APScheduler Jobs"] WebProc["Webhook Process
FastAPI Server"] end subgraph "Shared Infrastructure" ConfigStore["Configuration Store
Environment Variables"] LogStore["Log Storage
Rotating Log Files"] PIDStore["PID Management
Process Tracking"] end subgraph "External Systems" Mongo["MongoDB"] Telegram["Telegram API"] Superset["SuperSet Portal"] Email["Email Services"] end CLI["CLI Controller"] --> BotProc CLI --> SchedProc CLI --> WebProc BotProc --> ConfigStore SchedProc --> ConfigStore WebProc --> ConfigStore BotProc --> LogStore SchedProc --> LogStore WebProc --> LogStore BotProc --> PIDStore SchedProc --> PIDStore BotProc --> Telegram SchedProc --> Superset SchedProc --> Email WebProc --> Mongo BotProc --> Mongo SchedProc --> Mongo

Diagram sources

#

Detailed Component Analysis#

CLI Command Processing Flow#

The CLI orchestrates all operational modes through a centralized dispatch mechanism:

sequenceDiagram participant User as "Operator" participant CLI as "main.py" participant Daemon as "daemon.py" participant Server as "Server Module" participant Config as "config.py" User->>CLI : Execute command (bot/scheduler/webhook/update/send) CLI->>Config : get_settings() & setup_logging() CLI->>CLI : Parse arguments & validate alt Daemon Mode Requested CLI->>Daemon : daemonize(name) Daemon->>Daemon : Double-fork process Daemon->>Daemon : Redirect stdout/stderr Daemon->>Daemon : Write PID file CLI->>Config : Re-init logging in daemon end CLI->>Server : create_*_server(settings, daemon_mode) Server->>Config : Setup logging Server->>Server : Initialize services & dependencies Server->>User : Run server (blocking) Note over CLI,Server : Graceful shutdown on SIGTERM

Diagram sources

Section sources

Daemon Process Lifecycle#

The daemonization process ensures robust background operation:

flowchart TD Start(["Start Daemon"]) --> CheckRunning{"Already Running?"} CheckRunning --> |Yes| Exit["Exit with PID"] CheckRunning --> |No| FirstFork["First Fork
Detach from Terminal"] FirstFork --> SecondFork["Second Fork
Become Session Leader"] SecondFork --> WritePID["Write PID File"] WritePID --> RedirectIO["Redirect Stdout/Stderr
to Log File"] RedirectIO --> CloseFD["Close Unused File Descriptors"] CloseFD --> ReInitLogger["Re-initialize Logger
with new file handles"] ReInitLogger --> Ready["Daemon Ready"] Ready --> Shutdown["SIGTERM Received"] Shutdown --> Cleanup["Cleanup PID File & Resources"] Cleanup --> Exit

Diagram sources

Section sources

Scheduling Architecture with APScheduler#

The scheduler implements a comprehensive update automation system:

flowchart TD Init(["Scheduler Initialization"]) --> SetupTZ["Setup Asia/Kolkata Timezone"] SetupTZ --> CreateScheduler["Create AsyncIOScheduler"] CreateScheduler --> DefineJobs["Define Update Jobs
Multiple IST Times"] DefineJobs --> ScheduleOfficial["Schedule Official Data
Daily at 12:00 PM IST"] ScheduleOfficial --> StartScheduler["Start Scheduler"] StartScheduler --> Monitor["Monitor Running Jobs"] Monitor --> TriggerJob["Job Execution Triggered"] TriggerJob --> FetchUpdates["Fetch SuperSet Updates"] FetchUpdates --> ProcessEmails["Process Email Updates"] ProcessEmails --> SendNotifications["Send Telegram Notifications"] SendNotifications --> LogResult["Log Completion Metrics"] LogResult --> Monitor Monitor --> GracefulShutdown["Graceful Shutdown
on SIGTERM"] GracefulShutdown --> Cleanup["Shutdown Scheduler & Jobs"]

Diagram sources

Section sources

Logging Strategy and Configuration#

The logging system adapts to operational modes:

flowchart TD Start(["Logging Initialization"]) --> CheckDaemon{"Daemon Mode?"} CheckDaemon --> |No| ConsoleHandler["Console Handler
Development Output"] CheckDaemon --> |Yes| FileHandler["File Handler
Production Logs"] ConsoleHandler --> SetupFormat["Setup Log Format
Timestamp, Level, Module"] FileHandler --> SetupFormat SetupFormat --> SetLevel["Apply LOG_LEVEL
Environment Configurable"] SetLevel --> ReduceNoise["Suppress Third-Party Noise"] ReduceNoise --> InitComplete["Logging Ready"]

Diagram sources

Section sources

Server-Specific Architectures#

Telegram Bot Server#

The Telegram bot server provides user interaction capabilities:

  • Command handlers for user registration, status checking, and statistics

  • Administrative commands for system management

  • Integration with database services for user management

  • Polling-based message reception with graceful shutdown

Webhook Server#

The FastAPI-based webhook server exposes:

  • Health check endpoints for monitoring

  • Web push subscription management

  • Notification delivery endpoints

  • Statistics endpoints for operational insights

  • CORS configuration for cross-origin requests

Scheduler Server#

The scheduler server orchestrates automated operations:

  • Independent from Telegram bot for reliability

  • Configurable update cycles across multiple IST time slots

  • Official data scraping at designated intervals

  • Job persistence and restart handling

Section sources

#

Dependency Analysis#

The system exhibits clear dependency relationships:

graph TB subgraph "Core Dependencies" Config["Configuration
pydantic-settings"] APScheduler["APScheduler
asyncio scheduler"] Telegram["python-telegram-bot
Telegram API"] FastAPI["FastAPI
Web framework"] Uvicorn["Uvicorn
ASGI server"] end subgraph "Application Modules" Main["main.py
CLI orchestration"] Daemon["daemon.py
Process management"] Bot["bot_server.py
Telegram server"] Webhook["webhook_server.py
Web server"] Scheduler["scheduler_server.py
Scheduler server"] UpdateRunner["update_runner.py
Data processing"] NotifyRunner["notification_runner.py
Notification delivery"] end Main --> Config Main --> Daemon Bot --> Config Bot --> Telegram Webhook --> Config Webhook --> FastAPI Webhook --> Uvicorn Scheduler --> Config Scheduler --> APScheduler UpdateRunner --> Config NotifyRunner --> Config

Diagram sources

Section sources

#

Performance Considerations#

The architecture incorporates several performance optimization strategies:

Asynchronous Operations#

  • APScheduler integrated with AsyncIO for non-blocking job execution

  • Telegram bot uses asynchronous polling model

  • FastAPI server leverages async request handling

Resource Management#

  • Connection pooling for database clients

  • Lazy initialization of services to reduce startup overhead

  • Efficient message splitting for Telegram notifications

Scalability Patterns#

  • Decoupled server architecture allows independent scaling

  • Modular runner components enable selective service deployment

  • Environment-based configuration supports containerized deployments

#

Troubleshooting Guide#

Process Management Issues#

Common daemon-related problems and solutions:

  • Process already running: Check PID files in data/pids/ directory

  • Stale PID files: Manual cleanup required when processes terminate unexpectedly

  • Permission errors: Verify write permissions for logs and pids directories

Logging and Debugging#

  • Missing logs: Verify LOG_LEVEL environment variable and log file paths

  • Debug mode: Use -v flag for verbose output in development

  • Production logging: Ensure separate log files for bot and scheduler processes

Service Dependencies#

  • Telegram connectivity: Verify TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID

  • Database connectivity: Check MONGO_CONNECTION_STR configuration

  • Scheduler jobs: Confirm timezone settings and network connectivity for external APIs

Section sources

#

Conclusion#

The deployment architecture provides a robust foundation for operational excellence through:

  • Clear separation of concerns across dedicated server processes

  • Reliable daemon management with proper process isolation

  • Configurable scheduling with comprehensive monitoring capabilities

  • Flexible logging strategies suitable for diverse operational environments

  • Modular design enabling independent scaling and maintenance

The architecture successfully balances operational simplicity with production-grade reliability, supporting both development iteration and enterprise deployment scenarios.

Previous Formatting Services
Next Design Principles